home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / AddErrInfo.3 < prev    next >
Text File  |  1994-09-20  |  6KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_AddErrorInfo(3)  Tcl Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError -  record
  12.      information about errors
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      Tcl_AddErrorInfo(_i_n_t_e_r_p, _m_e_s_s_a_g_e)
  18.  
  19.      Tcl_SetErrorCode(_i_n_t_e_r_p, _e_l_e_m_e_n_t, _e_l_e_m_e_n_t, ... (char *) NULL)
  20.  
  21.      char *
  22.      Tcl_PosixError(_i_n_t_e_r_p)
  23.  
  24. ARGUMENTS
  25.      Tcl_Interp   *_i_n_t_e_r_p    (in)      Interpreter  in  which  to
  26.                                        record information.
  27.  
  28.      char         *_m_e_s_s_a_g_e   (in)      Identifying   string    to
  29.                                        record  in errorInfo vari-
  30.                                        able.
  31.  
  32.      char         *_e_l_e_m_e_n_t   (in)      String to  record  as  one
  33.                                        element of errorCode vari-
  34.                                        able.  Last _e_l_e_m_e_n_t  argu-
  35.                                        ment must be NULL.
  36. _________________________________________________________________
  37.  
  38.  
  39. DESCRIPTION
  40.      These procedures are used to manipulate two global variables
  41.      that  hold information about errors.  The variable errorInfo
  42.      holds a stack trace of the operations that were in  progress
  43.      when  an  error  occurred,  and  is  intended  to  be human-
  44.      readable.  The variable errorCode holds a list of items that
  45.      are  intended  to  be  machine-readable.   The first item in
  46.      errorCode identifies the class of error that occurred  (e.g.  |
  47.      POSIX  means  an  error occurred in a POSIX system call) and
  48.      additional elements in errorCode hold additional  pieces  of
  49.      information  that depend on the class.  See the Tcl overview
  50.      manual entry for details on the various formats  for  error-
  51.      Code.
  52.  
  53.      The errorInfo variable is gradually built  up  as  an  error
  54.      unwinds  through  the nested operations.  Each time an error
  55.      code  is  returned  to  Tcl_Eval  it  calls  the   procedure
  56.      Tcl_AddErrorInfo   to   add  additional  text  to  errorInfo
  57.      describing the command that  was  being  executed  when  the
  58.      error  occurred.   By the time the error has been passed all
  59.      the way back to the application, it will contain a  complete
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_AddErrorInfo(3)  Tcl Library Procedures
  71.  
  72.  
  73.  
  74.      trace of the activity in progress when the error occurred.
  75.  
  76.      It is sometimes useful  to  add  additional  information  to
  77.      errorInfo  beyond  what  can  be  supplied  automatically by
  78.      Tcl_Eval.  Tcl_AddErrorInfo may be used  for  this  purpose:
  79.      its  _m_e_s_s_a_g_e  argument  contains  an additional string to be
  80.      appended to errorInfo.   For  example,  the  source  command
  81.      calls  Tcl_AddErrorInfo to record the name of the file being
  82.      processed and the line number on which the  error  occurred;
  83.      for  Tcl  procedures,  the  procedure  name  and line number
  84.      within the procedure are recorded, and so on.  The best time
  85.      to call Tcl_AddErrorInfo is just after Tcl_Eval has returned
  86.      TCL_ERROR.  In calling Tcl_AddErrorInfo,  you  may  find  it
  87.      useful  to  use  the errorLine field of the interpreter (see
  88.      the Tcl_Interp manual entry for details).
  89.  
  90.      The procedure Tcl_SetErrorCode is used to set the  errorCode
  91.      variable.  Its _e_l_e_m_e_n_t arguments give one or more strings to
  92.      record in errorCode:  each _e_l_e_m_e_n_t will become one item of a
  93.      properly-formed    Tcl    list    stored    in    errorCode.
  94.      Tcl_SetErrorCode is typically invoked just before  returning
  95.      an   error.    If  an  error  is  returned  without  calling
  96.      Tcl_SetErrorCode then the Tcl interpreter automatically sets
  97.      errorCode to NONE.
  98.  
  99.      Tcl_PosixError sets the errorCode variable after an error in  |
  100.      a  POSIX  kernel  call.   It  reads the value of the errno C  |
  101.      variable and calls Tcl_SetErrorCode to set errorCode in  the  |
  102.      POSIX  format.  In addition, Tcl_PosixError returns a human-  |
  103.      readable diagnostic message for the error (this is the  same
  104.      value  that  will appear as the third element in errorCode).
  105.      It may be convenient to include this string as part  of  the
  106.      error message returned to the application in _i_n_t_e_r_p->_r_e_s_u_l_t.
  107.  
  108.      It is important to call the procedures described here rather
  109.      than   setting   errorInfo   or   errorCode   directly  with
  110.      Tcl_SetVar.  The reason for this is that the Tcl interpreter
  111.      keeps  information  about whether these procedures have been
  112.      called.  For example, the  first  time  Tcl_AppendResult  is
  113.      called  for  an  error,  it  clears  the  existing  value of
  114.      errorInfo and adds the error message  in  _i_n_t_e_r_p->_r_e_s_u_l_t  to
  115.      the variable before appending _m_e_s_s_a_g_e;  in subsequent calls,
  116.      it just appends the new _m_e_s_s_a_g_e.  When  Tcl_SetErrorCode  is
  117.      called,  it  sets  a flag indicating that errorCode has been
  118.      set;  this allows the Tcl interpreter to  set  errorCode  to
  119.      NONE  if  it  receives an error return when Tcl_SetErrorCode
  120.      hasn't been called.
  121.  
  122.      If the procedure Tcl_ResetResult is called, it clears all of
  123.      the  state  associated  with errorInfo and errorCode (but it
  124.      doesn't actually modify the variables).   If  an  error  had
  125.      occurred,  this will clear the error state to make it appear
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_AddErrorInfo(3)  Tcl Library Procedures
  137.  
  138.  
  139.  
  140.      as if no error had occurred after all.
  141.  
  142.  
  143. SEE ALSO
  144.      Tcl_ResetResult, Tcl_Interp
  145.  
  146.  
  147. KEYWORDS
  148.      error, stack, trace, variable
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.